package com.miniapp.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.miniapp.entity.BaseFile;
import org.springframework.web.multipart.MultipartFile;
import java.io.InputStream;

/**
 * 基础文件服务接口
 *
 * <p>定义文件上传、下载、删除及临时文件管理的标准接口
 * <p>支持临时文件与正式文件的转换功能
 *
 * @author yourName
 * @date 2025-09-06
 */
public interface BaseFileService extends IService<BaseFile> {

    /**
     * 上传文件（支持临时/正式文件标记）
     *
     * @param file 上传的文件，不能为空
     * @param isTemporary 是否为临时文件（true-临时，false-正式）
     * @param dir 存储目录（为空时自动生成）
     * @return 上传成功的文件实体
     */
    BaseFile uploadFile(MultipartFile file, boolean isTemporary, String dir);

    /**
     * 将临时文件转换为正式文件
     *
     * @param fileId 临时文件ID，不能为空
     * @param businessType 业务类型，不能为空
     * @param businessCode 业务编码，不能为空
     * @return 转换后的正式文件实体
     */
    BaseFile convertToFormalFile(Long fileId, String businessType, String businessCode);

    /**
     * 根据文件ID获取文件输入流
     *
     * @param fileId 文件ID，不能为空
     * @return 文件输入流（需调用方自行关闭）
     */
    InputStream getFileInputStream(Long fileId);

    /**
     * 删除文件（同时删除存储和数据库记录）
     *
     * @param fileId 文件ID，不能为空
     * @return 是否删除成功
     */
    boolean deleteFile(Long fileId);

    /**
     * 清理过期的临时文件
     *
     * <p>删除所有已过期且未转换为正式文件的临时文件
     *
     * @return 清理的文件数量
     */
    int cleanExpiredTemporaryFiles();
}
